The Bitmap Geometry Structure (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /

Chapter 5 - Bitmap Shapes / Bitmap Shapes Reference

The Bitmap Geometry Structure
The gxBitmap structure specifies the geometry of a bitmap shape. You can use this data structure when creating bitmap shapes with the GXNewBitmap function, when altering bitmap shapes with the GXGetBitmap and GXSetBitmap functions, and when directly editing bitmap shapes with the GXGetShapeStructure function.
The gxBitmap structure is defined as follows:
   typedef struct {
      char         *image;
      long         width;
      long         height;
      long         rowBytes;
      long         pixelSize;
      gxColorSpace space;
      gxColorSet   set;
      gxColorProfile profile;
   } gxBitmap;
Field Description

image
A pointer to the pixel image. When creating a bitmap, you can specify nil for this field to indicate that QuickDraw GX should allocate memory for the pixel image of the bitmap.
width
The width of the bitmap in pixels.
height
The height of the bitmap in pixels.
rowBytes
The number of bytes of the pixel image corresponding to each row of the bitmap. This value must be a positive even number.
pixelSize
The number of bits representing a single pixel in the pixel image. This value must be 1, 2, 4, 8, 16, or 32.
space
The color space that QuickDraw GX uses when interpreting the pixel values in the pixel image. When creating a bitmap, you may specify the gxNoSpace constant for this field to indicate that QuickDraw GX should choose a color space for you. If the value of the pixelSize field is 32, QuickDraw GX uses the value gxRGB32Space; if the pixel size is 16, QuickDraw GX uses gxRGB16Space; if the pixel size is 8 or less, QuickDraw GX uses gxIndexedSpace and creates the default color set for the pixel size, which is usually a grayscale color set.
set
The color set that QuickDraw GX uses when interpreting the pixel values of the pixel image. If the space field contains the value gxIndexedSpace, QuickDraw GX interprets the pixel values in the pixel image as indexes to this color set. If the bitmap's color space is not gxIndexedSpace, this field should be nil.
profile
The color matching information about the device on which the bitmap was created. You may provide a reference to a color profile object, or you may set the value of this field to nil.
Implementation Note
Version 1.0 of QuickDraw GX limits the bitmap width and the bitmap height to 32,767.
When creating a bitmap, you can allocate the memory for the pixel image of the bitmap yourself and store a pointer to it in the image field, or you can set the image field to nil, which indicates that QuickDraw GX should allocate the pixel image memory.
If you create the pixel image for a bitmap, you must pad the end of each row of the pixel image so that each row contains an even number of bytes. You must store the number of bytes per row in the rowBytes field, unless you are creating a bitmap with a pixel image in QuickDraw GX memory, in which case you want to set this field to 0.
If you set the image field to nil when creating a bitmap, QuickDraw GX does two things:

creates an uninitialized pixel image based on the bitmap width and height you specify in the width and height fields and the pixel size you specify in the pixelSize field
determines an appropriate rowBytes value

If you want to create a bitmap with a disk-based pixel image, you should specify the gxBitmapFileAliasImageValue constant for the image field.
If you specify the gxNoSpace constant for the space field, QuickDraw GX chooses an appropriate color space for you, based on the value of the pixelSize field.
If you specify the color space yourself, you must be sure the pixel size of that color space matches the value you indicate in the pixelSize field.
For a discussion of pixel images, bitmap width, bitmap height, and pixel size, see "Bitmap Geometries" beginning on page 5-5. For a detailed discussion of color spaces, color sets, and color profiles, see the chapter "Color and Color-Related Objects" in Inside Macintosh: QuickDraw GX Objects.
For examples of creating gxBitmap structures and bitmap shapes, see "Creating and Drawing Bitmaps" beginning on page 5-15.